<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>coap_attribute</title><link rel="stylesheet" type="text/css" href="docbook-xsl.css" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /></head><body><div xml:lang="en" class="refentry" lang="en"><a id="id1337"></a><div class="titlepage"></div><div class="refnamediv"><h2>NAME</h2><p>coap_attribute, coap_add_attr, coap_find_attr — Work with CoAP attributes</p></div><div class="refsynopsisdiv"><a id="_synopsis"></a><h2>SYNOPSIS</h2><p><span class="strong"><strong>#include &lt;coap2/coap.h&gt;</strong></span></p><p><span class="strong"><strong>coap_attr_t *coap_add_attr(coap_resource_t *<span class="emphasis"><em>resource</em></span>, coap_str_const_t
*<span class="emphasis"><em>name</em></span>, coap_str_const_t *<span class="emphasis"><em>value</em></span>, int <span class="emphasis"><em>flags</em></span>);</strong></span></p><p><span class="strong"><strong>coap_attr_t *coap_find_attr(coap_resource_t *<span class="emphasis"><em>resource</em></span>, coap_str_const_t
*<span class="emphasis"><em>name</em></span>);</strong></span></p><p>Link with <span class="strong"><strong>-lcoap-2</strong></span>, <span class="strong"><strong>-lcoap-2-gnutls</strong></span>,
<span class="strong"><strong>-lcoap-2-openssl</strong></span> or
<span class="strong"><strong>-lcoap-2-tinydtls</strong></span> depending on your (D)TLS library
type.</p></div><div class="refsect1"><a id="_description"></a><h2>DESCRIPTION</h2><p>CoAP Resources on a CoAP Server need to be created, updated etc. The URI in
the request packet defines the resource to work with, with possibly the Query
referring to a sub-resource.
When resources are configured on the CoAP server, the URI to match against
is specified.
Callback Handlers are then added to the resource to handle the different
request methods.
Adding Attributes allows textual information to be added to the resource
which can then be reported back to any client doing a "GET .well-known/core"
request.</p><p>Attributes are automatically freed when a Resource is deleted.</p><p>The <span class="strong"><strong>coap_add_attr</strong></span>() function
registers a new attribute called <span class="emphasis"><em>name</em></span> for the <span class="emphasis"><em>resource</em></span>.
The value of the attribute is <span class="emphasis"><em>value</em></span>.</p><p><span class="emphasis"><em>flags</em></span> can be one or more of the following, which, if set, defines what is
to be internally freed off when the attribute is deleted with
<span class="strong"><strong>coap_delete_resource</strong></span>().</p><div class="horizontal"><table class="horizontal" cellpadding="4px" style="border: none;"><colgroup><col /><col /></colgroup><tbody valign="top"><tr><td style="" valign="top">
<p>
<span class="strong"><strong>COAP_ATTR_FLAGS_RELEASE_NAME</strong></span>
</p>
</td><td style="" valign="top">
<p>
Free off <span class="emphasis"><em>name</em></span> when attribute is deleted with <span class="strong"><strong>coap_delete_resource</strong></span>().
</p>
</td></tr><tr><td style="" valign="top">
<p>
<span class="strong"><strong>COAP_ATTR_FLAGS_RELEASE_VALUE</strong></span>
</p>
</td><td style="" valign="top">
<p>
Free off <span class="emphasis"><em>value</em></span> when attribute is deleted with <span class="strong"><strong>coap_delete_resource</strong></span>().
</p>
</td></tr></tbody></table></div><p>The <span class="strong"><strong>coap_find_attr</strong></span>() function returns the attribute with the <span class="emphasis"><em>name</em></span>,
if found, associated with <span class="emphasis"><em>resource</em></span>.</p></div><div class="refsect1"><a id="_return_values"></a><h2>RETURN VALUES</h2><p><span class="strong"><strong>coap_add_attr</strong></span>() function return a pointer to
the attribute that was created or NULL if there is a malloc failure.</p><p><span class="strong"><strong>coap_find_attr</strong></span>() function returns a pointer to the first matching
attribute or NULL if the <span class="emphasis"><em>name</em></span> was not found.</p></div><div class="refsect1"><a id="_example"></a><h2>EXAMPLE</h2><p><span class="strong"><strong>Initialize Resources</strong></span></p><pre class="programlisting">#include &lt;coap2/coap.h&gt;

static void
init_resources(coap_context_t *ctx) {

  coap_resource_t *r;

  /* Create a resource to return general information */
  r = coap_resource_init(NULL, 0);
  coap_register_handler(r, COAP_REQUEST_GET, hnd_get_index);

  /* Document resource for .well-known/core request */
  coap_add_attr(r, coap_make_str_const("ct"), coap_make_str_const("0"), 0);
  coap_add_attr(r, coap_make_str_const("title"),
                coap_make_str_const("\"General Info\""), 0);

  coap_add_resource(ctx, r);

  /* Create a resource to return return or update time */
  r = coap_resource_init(coap_make_str_const("time"),
                         COAP_RESOURCE_FLAGS_NOTIFY_CON);
  coap_resource_set_get_observable(r, 1);
  coap_register_handler(r, COAP_REQUEST_GET, hnd_get_time);
  coap_register_handler(r, COAP_REQUEST_PUT, hnd_put_time);
  coap_register_handler(r, COAP_REQUEST_DELETE, hnd_delete_time);

  /* Document resource for .well-known/core request */
  coap_add_attr(r, coap_make_str_const("ct"), coap_make_str_const("0"), 0);
  coap_add_attr(r, coap_make_str_const("title"),
                coap_make_str_const("\"Internal Clock\""), 0);
  coap_add_attr(r, coap_make_str_const("rt"), coap_make_str_const("\"secs\""),
                0);
  coap_add_attr(r, coap_make_str_const("if"), coap_make_str_const("\"clock\""),
                0);

  coap_add_resource(ctx, r);

}</pre></div><div class="refsect1"><a id="_see_also"></a><h2>SEE ALSO</h2><p><a href="man_coap_resource.html" target="_self"><span class="strong"><strong>coap_resource</strong></span>(3)</a> and <a href="man_coap_handler.html" target="_self"><span class="strong"><strong>coap_handler</strong></span>(3)</a></p></div><div class="refsect1"><a id="_further_information"></a><h2>FURTHER INFORMATION</h2><p>See RFC7252 ‘The Constrained Application Protocol (CoAP)’ for further
information.</p></div><div class="refsect1"><a id="_bugs"></a><h2>BUGS</h2><p>Please report bugs on the mailing list for libcoap:
<a class="ulink" href="mailto:libcoap-developers@lists.sourceforge.net" target="_top">libcoap-developers@lists.sourceforge.net</a></p></div><div class="refsect1"><a id="_authors"></a><h2>AUTHORS</h2><p>The libcoap project &lt;<a class="ulink" href="mailto:libcoap-developers@lists.sourceforge.net" target="_top">libcoap-developers@lists.sourceforge.net</a>&gt;</p></div></div></body></html>